/**
 * Copyright (C) 2012 Foxit Corporation.
 * All Rights Reserved.
 *
 * The following code is copyrighted and contains proprietary information and trade secrets of Foxit Corporation.<br> 
 * You can only redistribute files listed below to customers of your application, under a written SDK license agreement with Foxit.<br>
 * You cannot distribute any part of the SDK to general public, even with a SDK license agreement.<br>
 * Without SDK license agreement, you cannot redistribute anything.
 * 
 * @file	fpdfdocument.h
 * @brief	Header file for the PDF document module. 
 * @details	The document module offers: 
 *			1. Basic methods for doing some operation on documents and pages, such as loading, parsing, saving and closing. 
 *			2. Methods for getting some basic information of documents or pages. 
 *			3. Methods for getting useful information of bookmarks. 
 *			
 *			Before doing operations on documents or pages, users should load documents or pages first.
 *			And when finishing their operations, users should remeber to close pages or docuemnts in time.
 * @note	If you want to purchase Foxit PDF SDK license and use ANY of the following functions, please
 *			request for enabling Document module explicitly. 
 */

 /** 
 * @addtogroup FGSPDFDOC PDF Document
 * @brief Methods in this module are included in fpdfdocument.h.
 */
 /**@{*/

#ifndef __FGSPDFDOCUMENT__
#define __FGSPDFDOCUMENT__

#include "fpdfbase.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief	Load a PDF document
 *
 * @details	Document loading is a progressive process. It might take a long time to
 *			load a document, especially when a file is corrupted, and it will try to
 *			recover the document contents by scanning the whole file. 
 *
 * @param[in] fileStream	Reference to an input file stream.
 *							This reference must be kept valid as long as the document is open.
 * @param[in] password		Reference to a CFDataRef for the password.
 *							Or <b>NULL</b> for no password.
 * @param[out] document     Pointer to FGSPDFDocumentRef to recerives the PDF document.
 *
 * @return	::kFGSErrorSuccess means close the document successfully. 
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFDocLoadDoc(FGSFileStreamInRef fileStream, CFDataRef password, FGSPDFDocumentRef *document);

/**
 * @brief	Load a PDF document.
 *
 * @details	Document loading is a progressive process. It might take a long time to
 *			load a document, especially when a file is corrupted, and it will try to
 *			recover the document contents by scanning the whole file. <br>
 *
 * @param[in] pdfFile		Reference to a CFDataRef for the file name.
 * @param[in] start			The PDF file offset.
 * @param[in] size			The PDF file size.
 * @param[out] document     Pointer to FGSPDFDocumentRef to recerives the PDF document.
 *
 * @return	::kFGSErrorSuccess means close the document successfully. 
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFDocLoadDocEx(CFStringRef pdfFile, SInt32 start, SInt32 size, FGSPDFDocumentRef *document);

/**
 * @brief	Close a PDF document and release all associated resources.
 *
 * @param[in] document		Reference to a PDF document.
 *
 * @return	::kFGSErrorSuccess means close the document successfully. 
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFDocCloseDoc(FGSPDFDocumentRef document);

/**
* @brief	Reload a document after it has been modified .
*
* @details The document reloading is a progressive process. It might take a long time to
*			reload the document. 
*			Actually, this function just parses the document again after it has been modified. 
*
* @param[in] document		Reference to a PDF document. 
* @param[in] pdfStream		Reference to an input file stream.
* @param[in] password		Reference to a CFDataRef for the password.
*							Or <b>NULL</b> for no password.
*
* @return	::kFGSErrorSuccess means reload the document successfully. 
*			For more definitions please see enum definitions <b>FGSErrorRet</b>.
*
*/
FGSErrorRet FGSPDFDocReloadDocument(FGSPDFDocumentRef document, FGSFileStreamInRef pdfStream, CFDataRef password);

/**
 * @brief	Save the modified document to a new file.
 *
 * @param[in] document		Reference to a PDF document.
 * @param[in] file			Reference to a FGSFileStreamOutRef for output file stream.
 * @param[in] flag			The saving flags. See macro definitions:
 *							<ul>
 *							<li>::kFGSPDFSaveAsIncremental</li>
 *							<li>::kFGSPDFSaveAsNooriginal</li>
 *							</ul>
 * @param[in] pause			A callback mechanism allowing the document saving process
 *							to be paused before it's finished. This can be <b>NULL</b> if you
 *							don't want to pause.Only valid if pass kFGSPDFSaveAsProgressive flag in
 *							in calling this method.
 * @param[in] security      Reference to a PDF security.
 *
 * @return	::kFGSErrorSuccess means save the document successfully. 
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFDocStartSavingDoc(FGSPDFDocumentRef document, FGSFileStreamOutRef file, FGSPDFSavingFlag flag, FGSPause *pause, FGSPDFSecurityRef security);

/**
 * @brief	Continue saving the modified document to a new file.
 *
 * @param[in] document		Reference to a PDF document.
 * @param[in] pause			Pointer ot a callback mechanism allowing the document saving process
 *							to be paused before it's finished. This can be <b>NULL</b> if you
 *							don't want to pause.
 *
 * @return	::kFGSErrorSuccess means save the document successfully. 
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFDocContinueSavingDoc(FGSPDFDocumentRef document, FGSPause *pause);

/**
 * @name Macro definitions for string of the document metatext key.
 */
/**@{*/
/** @brief The document metatext key : "Title". */
extern const CFStringRef kFGSPDFDocMetaTextTitleKey;
/** @brief The document metatext key : "Author". */
extern const CFStringRef kFGSPDFDocMetaTextAuthorKey;
/** @brief The document metatext key : "Subject". */
extern const CFStringRef kFGSPDFDocMetaTextSubjectKey;
/** @brief The document metatext key : "Keywords". */
extern const CFStringRef kFGSPDFDocMetaTextKeywordsKey;
/** @brief The document metatext key : "Creator". */
extern const CFStringRef kFGSPDFDocMetaTextCreatorKey;
/** @brief The document metatext key : "Producer". */
extern const CFStringRef kFGSPDFDocMetaTextProducerKey;
/** @brief The document metatext key : "CreationDate". */
extern const CFStringRef kFGSPDFDocMetaTextCreationDateKey;
/** @brief The document metatext key : "ModDate". */
extern const CFStringRef kFGSPDFDocMetaTextModDateKey;
/**@}*/

/**
 * @brief	Get the information string about the document, such as the creator, the modification date, etc.
 *
 * @details	The string is output in Unicode, using UTF-16LE format. It's terminated by
 *			two consecutive zero bytes. 
 *
 * @param[in] document		Reference to a PDF document
 * @param[in] key			A byte string for the information key. 
 *							Currently it can be one of the followings:
 *							<ul>
 *							<li>"Title"</li> 
 *							<li>"Author"</li>
 *							<li>"Subject"</li>
 *							<li>"Keywords"</li>
 *							<li>"Creator"</li>
 *							<li>"Producer"</li>
 *							<li>"CreationDate"</li>
 *							<li>"ModDate"</li>
 *							<li>Some other custom information keys, if they're supported by the PDF file.</li>
 *							</ul>
 *
 * @return	The string of the meta text, user should free the string by call CFRelease.
 *
 */
CFStringRef FGSPDFDocCopyMetaText(FGSPDFDocumentRef document, CFStringRef key);

/**
 * @brief	Get permission flags specified by a PDF document.
 *
 * @param[in] document		Reference to a PDF document which is returned by the function ::FGSPDFDocLoadDoc.
 *
 * @return	The permission flag.
 */
FGSPDFPermissions FGSPDFDocGetPermissions(FGSPDFDocumentRef document);

/**
 * @brief Judge a pdf document whether is a wrapper document.
 *
 * @param[in] document		Reference to a PDF document.
 *
 * @return	A Boolean receiving the result.
 *
 */
Boolean FGSPDFDocIsWrapper(FGSPDFDocumentRef document);

/**
 * @brief Get the wrapper type from a pdf document.
 *
 * @param[in] document		Reference to a PDF document.
 *
 * @return	The wrapper type data.
 *
 */
CFStringRef FGSPDFDocGetWrapperType(FGSPDFDocumentRef document);

/**
 * @brief Get the wrapper offset from a pdf document.
 *
 * @param[in] document		Reference to a PDF document.
 *
 * @return	The offset value.
 *
 */
SInt32 FGSPDFDocGetWrapperOffset(FGSPDFDocumentRef document);

/**
 * @brief Get the first child of a bookmark item, or the first top level bookmark item.
 *
 * @param[in] document		Reference to a PDF document.
 * @param[in] parent		Reference to the parent bookmark. 
 *							This can be <b>NULL</b> if you want to get the first top level item.
 *
 * @return	The reference to the first child or the first top level bookmark item.
 *
 */
FGSPDFBookmarkRef FGSPDFBookmarkGetFirstChild(FGSPDFDocumentRef document, FGSPDFBookmarkRef parent);

/**
 * @brief Get the next sibling of a bookmark item.
 *
 * @param[in] document		Reference to a PDF document.
 * @param[in] bookmark		Reference to a PDF bookmark.

 *
 * @return	The reference of the next sibling.
 *
 */
FGSPDFBookmarkRef FGSPDFBookmarkGetNextSibling(FGSPDFDocumentRef document, FGSPDFBookmarkRef bookmark);

/**
 * @brief Get the title of a bookmark.
 *
 * @param[in] bookmark		Reference to a PDF bookmark.
 *
 * @return	The string of bookmark title, user should free the string by call CFRelease.
 *
 */
CFStringRef FGSPDFBookmarkCopyTitle(FGSPDFBookmarkRef bookmark);

/**
 * @brief Get designated color of a bookmark item.
 * 
 * @param[in] bookmark      Reference to a PDF bookmark.
 * 
 * @return The color of the annotation.
 */
UInt32 FGSPDFBookmarkGetColor(FGSPDFBookmarkRef bookmark);
      
/**
 * @brief Get designated font style for a bookmark item.
 *
 * @param[in] bookmark      Reference to a PDF bookmark.
 *
 * @return A number indicating the font style.
 */
FGSBookmarkFontStyle FGSPDFBookmarkGetFontStyle(FGSPDFBookmarkRef bookmark);

/**
 * @brief Get the index of a page, to which the input bookmark is pointed.
 *
 * @details Some bookmarks might not point to a page, while some bookmarks might have more than one destination.
 *
 * @param[in] document		Reference to a PDF document.
 * @param[in] bookmark		Reference to a PDF bookmark.
 *
 * @return	The index of the page.
 *
 */
SInt32 FGSPDFBookmarkGetPageIndex(FGSPDFDocumentRef document, FGSPDFBookmarkRef bookmark);

/**
 * @brief Get the action(s) associated with a particular bookmark
 *
 * @param[in] document		Reference to a PDF document.
 * @param[in] bookmark		Reference to a PDF bookmark.		
 *
 * @return	The reference of the first action.
 *
 */
FGSPDFActionRef FGSPDFBookmarkGetAction(FGSPDFDocumentRef document, FGSPDFBookmarkRef bookmark);

#ifdef __cplusplus
};
#endif

#endif // __FGSPDFDOCUMENT__
/**@}*/

